<html>

<head>

<title>ADODB Session Management Manual</title>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<XSTYLE

    body,td {font-family:Arial,Helvetica,sans-serif;font-size:11pt}

    pre {font-size:9pt}

    .toplink {font-size:8pt}

    />

</head>    

<body bgcolor="#FFFFFF">

<h3>ADODB Session Management Manual</h3>

<p>

V4.21 20 Mar 2004 (c) 2000-2004 John Lim (jlim#natsoft.com.my)

<p> <font size=1>This software is dual licensed using BSD-Style and LGPL. This 

  means you can use it in compiled proprietary and commercial products. </font> 

<p>Useful ADOdb links:  <a href=http://php.weblogs.com/adodb>Download</a> &nbsp; <a href=http://php.weblogs.com/adodb_manual>Other Docs</a>



<h3>Introduction</h3>

<p> 

We store state information specific to a user or web client in session variables. These session variables 

 persist throughout a session, as the user moves from page to page. 

<p>

To use session variables, call session_start() at the beginning of your web page, 

before your HTTP headers are sent. Then for every variable you want to keep alive 

for the duration of the session, call session_register($variable_name). By default, 

the session handler will keep track of the session by using a cookie. You can save objects

 or arrays in session variables also.

<p>The default method of storing sessions is to store it in a file. However if 

  you have special needs such as you:

<ul>

  <li>Have multiple web servers that need to share session info</li>

  <li>Need to do special processing of each session</li>

  <li>Require notification when a session expires</li>

</ul>

<p>Then the ADOdb session handler provides you with the above additional capabilities 

  by storing the session information as records in a database table that can be 

  shared across multiple servers. 

<p><b>Important Upgrade Notice:</b> Since ADOdb 4.05, the session files have been moved to its own folder, adodb/session. This is a rewrite

of the session code by Ross Smith. The old session code is in adodb/session/old. 

<h4>ADOdb Session Handler Features</h4>

<ul>

<li>Ability to define a notification function that is called when a session expires. Typically

used to detect session logout and release global resources.

<li>Optimization of database writes. We crc32 the session data and only perform an update

to the session data if there is a data change.

<li>Support for large amounts of session data with CLOBs (see adodb-session-clob.php). Useful

for Oracle.

<li>Support for encrypted session data, see adodb-cryptsession.inc.php. Enabling encryption 

is simply a matter of including adodb-cryptsession.inc.php instead of adodb-session.inc.php.

</ul>

<h3>Setup</h3>

<p>There are 3 session management files that you can use:

<pre>

adodb-session.php        : The default

adodb-session-clob.php   : Use this if you are storing DATA in clobs

adodb-cryptsession.php   : Use this if you want to store encrypted session data in the database



<strong>Examples</strong>

 <font color=#004040>

    include('adodb/adodb.inc.php');

    

<b>    $ADODB_SESSION_DRIVER='mysql';

    $ADODB_SESSION_CONNECT='localhost';

    $ADODB_SESSION_USER ='scott';

    $ADODB_SESSION_PWD ='tiger';

    $ADODB_SESSION_DB ='sessiondb';</b>

    

    <b>include('adodb/session/adodb-session.php');</b>

    session_start();

    

    #

    # Test session vars, the following should increment on refresh

    #

    $_SESSION['AVAR'] += 1;

    print "&lt;p>\$_SESSION['AVAR']={$_SESSION['AVAR']}&lt;/p>";

</font>

To force non-persistent connections, call adodb_session_open first before session_start():

 <font color=#004040>

    include('adodb/adodb.inc.php');

    

<b>    $ADODB_SESSION_DRIVER='mysql';

    $ADODB_SESSION_CONNECT='localhost';

    $ADODB_SESSION_USER ='scott';

    $ADODB_SESSION_PWD ='tiger';

    $ADODB_SESSION_DB ='sessiondb';</b>

    

    <b>include('adodb/session/adodb-session.php');

    adodb_sess_open(false,false,false);</b>

    session_start();

 </font color=#004040>

To use a encrypted sessions, simply replace the file:

 <font color=#004040>

    include('adodb/adodb.inc.php');

    

<b>    $ADODB_SESSION_DRIVER='mysql';

    $ADODB_SESSION_CONNECT='localhost';

    $ADODB_SESSION_USER ='scott';

    $ADODB_SESSION_PWD ='tiger';

    $ADODB_SESSION_DB ='sessiondb';

    

    include('adodb/session/adodb-cryptsession.php');</b>

    session_start();

    </font>

And the same technique for adodb-session-clob.php:

 <font color=#004040>

    include('adodb/adodb.inc.php');

    

<b>    $ADODB_SESSION_DRIVER='mysql';

    $ADODB_SESSION_CONNECT='localhost';

    $ADODB_SESSION_USER ='scott';

    $ADODB_SESSION_PWD ='tiger';

    $ADODB_SESSION_DB ='sessiondb';

    

    include('adodb/session/adodb-session-clob.php');</b>

    session_start();

    </font>

 <h4>Installation</h4>

 1. Create this table in your database (syntax might vary depending on your db):

 <a name=sessiontab></a> <font color=#004040>

  create table sessions (

       SESSKEY char(32) not null,

       EXPIRY int(11) unsigned not null,

       EXPIREREF varchar(64),

       DATA text not null,

      primary key (sesskey)

  );</font>

  

  For the adodb-session-clob.php version, create this:

   <font color=#004040>

    create table sessions (

       SESSKEY char(32) not null,

       EXPIRY int(11) unsigned not null,

       EXPIREREF varchar(64),

       DATA CLOB,

      primary key (sesskey)

  );</font>



  2. Then define the following parameters. You can either modify

     this file, or define them before this file is included:

      <font color=#004040>

    $ADODB_SESSION_DRIVER='database driver, eg. mysql or ibase';

    $ADODB_SESSION_CONNECT='server to connect to';

    $ADODB_SESSION_USER ='user';

    $ADODB_SESSION_PWD ='password';

    $ADODB_SESSION_DB ='database';

    $ADODB_SESSION_TBL = 'sessions'; # setting this is optional

	</font>

    When the session is created, $<b>ADODB_SESS_CONN</b> holds the connection object.

    

  3. Recommended is PHP 4.0.6 or later. There are documented session bugs 

  in earlier versions of PHP.

</pre>



    <h3>Notifications</h3>

<p>If you want to receive notification when a session expires, then

     tag the session record with a <a href="#sessiontab">EXPIREREF</a> tag (see the 

    definition of the sessions table above).  Before any session record is deleted,

	ADOdb will call a notification function, passing in the EXPIREREF.

<p>

When a session is first created, we check a global variable $ADODB_SESSION_EXPIRE_NOTIFY.

    This is an array with 2 elements, the first being the name of the session variable

    you would like to store in the EXPIREREF field, and the 2nd is the 

    notification function's name.

	<p>

	 Suppose we want to be notified when a user's session 

    has expired, based on the userid. The user id in the global session variable $USERID.

	The function name is 'NotifyFn'. So we define:

    <pre> <font color=#004040>

        $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');

    </font></pre>

    And when the NotifyFn is called (when the session expires), we pass the $USERID 

    as the first parameter, eg. NotifyFn($userid, $sesskey). The session key (which is 

	the primary key of the record in the sessions table) is the 2nd parameter.

  <p>

    Here is an example of a Notification function that deletes some records in the database

	and temporary files:

    <pre><font color=#004040>

        function NotifyFn($expireref, $sesskey)

        {

        global $ADODB_SESS_CONN; # the session connection object



          $user = $ADODB_SESS_CONN->qstr($expireref);

          $ADODB_SESS_CONN->Execute("delete from shopping_cart where user=$user");

          system("rm /work/tmpfiles/$expireref/*");

        }</font>

    </pre>

	<p>

 	NOTE 1: If you have register_globals disabled in php.ini, then you will have to

	manually set the EXPIREREF. E.g.

	  <pre> <font color=#004040>

	    $GLOBALS['USERID'] =& $_SESSION['USERID'];

        $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');

    </font></pre>

    <p>

    NOTE 2: If you want to change the EXPIREREF after the session record has been

    created, you will need to modify any session variable to force a database

    record update.



<h4>Neat Notification Tricks</h4>



<p><i>ExpireRef</i> normally holds the user id of the current session.

<p>

1. You can then write a session monitor, scanning expireref to see

who is currently logged on.

<p>

2. If you delete the sessions record for a specific user, eg.

<pre>

delete from sessions where expireref = '$USER'

</pre>

then the user is logged out. Useful for ejecting someone from a

site.

<p>

3. You can scan the sessions table to ensure no user

can be logged in twice. Useful for security reasons.

<p>



<h3>Compression/Encryption Schemes</h3>

Since ADOdb 4.05, thanks to Ross Smith,  multiple encryption and compression schemes are supported.

  Currently, supported:

<pre>

  MD5Crypt (crypt.inc.php)

  MCrypt

  Secure (Horde's emulation of MCrypt, if MCrypt module is not available.)

  GZip

  BZip2

</pre>

These are stackable. E.g. 

<pre>

ADODB_Session::filter(new ADODB_Compress_Bzip2());

ADODB_Session::filter(new ADODB_Encrypt_MD5());

</pre>

will compress and then encrypt the record in the database.

<p>

Also see the <a href=docs-adodb.htm>core ADOdb documentation</a>.

</body>

</html>